Image Acquisition

Image Acquisition

The SDK supports the following 2 image acquisition methods: callback and polling. Select one as needed.

• Callback: Acquire images via callback.
• Polling: Acquire images via polling.

Attention

These two methods cannot be used at the same time.

Acquire Images via Callback

You can register a callback for image acquisition in SDK. After getting images, SDK will call the custom callback function.

Application: Call MV_CC_RegisterImageCallBackEx() or MV_CC_RegisterImageCallBackEx2() to register a callback.

Attention

• Time-consuming operations and thread locks are not recommended, because adding them may block the callback.
• pData is invalid and cannot be used again after callback ends.
• When registering a callback via MV_CC_RegisterImageCallBackEx2(), you can release the buffer manually or automatically.

The API calling flow is as follows:

1. Call MV_CC_SetImageNodeNum() to set the appropriate number of buffer nodes.

   Note

   Set the appropriate number of buffer nodes as needed. Major factors include: camera frame rate, image solution, and computer configuration such as main board performance and memory.

2. Call MV_CC_RegisterImageCallBackEx2() to register an image processing function.
3. Call MV_CC_StartGrabbing() to start acquiring images.
4. After receiving the images, SDK will process images via the custom image processing function.

The following sample codes show how to acquire images via callback:

• Customize the callback function:

  FrameInfoCallBack2 = winfun_ctype(None, POINTER(MV_FRAME_OUT), c_void_p, c_bool)
  
  def image_callback2(pstFrame, pUser, bAutoFree):
          stFrame = cast(pstFrame, POINTER(MV_FRAME_OUT)).contents
          if stFrame:
              print ("get one frame: Width[%d], Height[%d], nFrameNum[%d]" % (stFrame.stFrameInfo.nWidth, stFrame.stFrameInfo.nHeight, stFrame.stFrameInfo.nFrameNum))
          
          #Non-automatic release mode. Releasing resources manually is required.
          if bAutoFree == False :
              if pUser != None: 
                  User = ctypes.cast(pUser, ctypes.py_object).value
                  User.MV_CC_FreeImageBuffer(stFrame)
              else :
                  print ("user is null, invalid")
          
  
  CALL_BACK_FUN2 = FrameInfoCallBack2(image_callback2)

• Register a callback for image grabbing and start acquiring images.

  #Register an image grabbing callback
  ret = cam.MV_CC_RegisterImageCallBackEx2(CALL_BACK_FUN2, ctypes.py_object(cam), True)
  if ret != 0:
      print ("register image callback fail! ret[0x%x]" % ret)
      sys.exit()
  
  # Start grabbing images
  ret = cam.MV_CC_StartGrabbing()
  if ret != 0:
      print ("start grabbing fail! ret[0x%x]" % ret)
      sys.exit()

Acquire Images via Polling

You can create a thread and get images via polling in the thread.

The API calling flow is as follows:

1. Call MV_CC_SetImageNodeNum() to set the appropriate number of buffer nodes in SDK.

   Note

   • The SDK receives the image data from the camera and caches it internally for external calls. If the upper layer calls are slow and the number of buffer nodes is limited, the SDK will have insufficient buffer to receive new image data, resulting in frame loss.
   • Set the appropriate number of buffer nodes as needed. Major factors include camera frame rate, image solution, and computer configuration such as main board performance and memory.

2. Call MV_CC_StartGrabbing() to start acquiring images.

3. Call MV_CC_GetImageBuffer() in the application layer to get frame data in the specified pixel format.

   Note

   • You can set the timeout duration of this API. SDK waits for returned data before timeout.
   • When getting image data, you can configure API calling frequency in the upper application layer according to the camera frame rate.

4. Process images through buffer operation.

5. Call MV_CC_FreeImageBuffer() to release the buffer.

   Note

   • After calling MV_CC_FreeImageBuffer(), buffer will be returned to SDK and be invalid.
   • The API MV_CC_GetImageBuffer() supports setting timeout duration. SDK waits for returned data before timeout.

The following sample codes show how to acquire images via polling:

1. Customize the thread function to receive and process images.

   # Customize the thread function
   def work_thread(cam=0, pData=0, nDataSize=0):
       stOutFrame = MV_FRAME_OUT()  
       memset(byref(stOutFrame), 0, sizeof(stOutFrame))
       while True:
           ret = cam.MV_CC_GetImageBuffer(stOutFrame, 1000)
           if None != stOutFrame.pBufAddr and 0 == ret:
               print ("get one frame: Width[%d], Height[%d], nFrameNum[%d]"  % (stOutFrame.stFrameInfo.nWidth, stOutFrame.stFrameInfo.nHeight, stOutFrame.stFrameInfo.nFrameNum))
               nRet = cam.MV_CC_FreeImageBuffer(stOutFrame)
           else:
               print ("no data[0x%x]" % ret)
           if g_bExit == True:
               break

2. Start grabbing images.

   # Start grabbing images
   ret = cam.MV_CC_StartGrabbing()
   if ret != 0:
       print ("start grabbing fail! ret[0x%x]" % ret)
       sys.exit()
   
   try:
       hThreadHandle = threading.Thread(target=work_thread, args=(cam, None, None))
       hThreadHandle.start()
   except:
       print ("error: unable to start thread")

Previous: Event and Exception

Next: Image Processing